Running the Agent as a Windows Service (DAI Run Agent)

On Microsoft Windows machines, you can configure the DAI Run Agent ("Run Agent") to run as a service. Running as a service enables the Run Agent to run continuously in the background even when users log on and off the machine. You can also run multiple Run Agent services on the same machine if the machine has sufficient memory and processing capability.

For information about the DAI Run Agent, see About Execution Environments and Agents. For information about DAI-supported Windows operating systems, see the Prerequisites page.

note

The option to configure the Run Agent as a Windows service is available in DAI version 7.2 and later.

Managing the Run Agent with the Windows Services Manager

Once you create a service, you can administer it using the Windows Windows Services Manager (shown below) or using the Run Agent command (eggplantDAIRunAgent.exe) at a command-line interface (CLI). Information about creating, starting, stopping, and removing services with the Run Agent command is provided below.

The Windows Services Manager lists the Name, Description, Status, Startup Type, and Log On As information about each service. It also provides the options to start, stop, and configure how you want the service to start (Automatic or Manual), including setting its startup to be dependent upon the DAI Server service starting, if you plan to run your Run Agent and DAI Server as services on the same machine. For more information about Windows service controls, see Introduction to Windows Service Applications.

To open the Windows Services Manager:

1. On your Windows machine, type services in the Type here to search field in your taskbar. The Services app should be suggested.

2. Click the suggested Services app. The Windows Services Manager shown below opens.

User Accounts and Windows Services

There are two types of user accounts associated with creating and running Windows services:

• The Windows user account with Administrator privileges you will be required to use to log onto the machine, and create and administer the service. Note that even with a user account that has administrator privileges, you may need to launch the command (CMD) shell with "Run as Administrator".
• The Local System account that runs the Run Agent service once it is created as mentioned above. See this article for more information about Windows service accounts.

Creating a Windows Service for the Run Agent

The Run Agent provides a command for installing a Run Agent service at the command line (CLI). Use the Run Agent command (eggplantDAIRunAgent.exe) with the --win-service install argument and other agent run setting arguments to create a Windows service. See Run Agent Service Options below for information about settings and arguments. The Run Agent install service command creates the service with the following settings by default:

• Name: DAI Run Agent as shown above if another name is not specified with the install command.
• Startup Type: Automatic setting the serivce to start automatically whenever the host machine restarts.
• Log On As: Local System the user account that runs the service.

Once the service is created, you can manage it using either the Windows Services Manager or the Run Agent command at the CLI.

Step by Step: Installing a Run Agent Service

1. Log onto the Windows machine where you want your Run Agent as a service with a user that has Administrative privileges on the machine.
2. Install the DAI Run Agent as described in Install an Agent.
3. Determine the settings you want your agent to run with and create the Run Agent command with the arguments you need for those settings. See Run Agent Install Service Arguments for information about Run Agent service command options. See Running the Agent in Command Line Mode for information about run settings and arguments for the Run Agent.
4. Launch a command shell on your Windows machine by typing cmd in the Search bar in the Taskbar and, when the Command Prompt app (CMD) is suggested, right-clicking it and choosing "Run as Administrator". The CMD app opens with a command prompt.
5. Enter the Run Agent command with the arguments you want (created in Step 1 above) at the command prompt and press Enter. For example:

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service install --service-name "DAI Agent Service 1" --service-desc "This is a test service"

The command above creates a Windows service named "DAI Agent Service 1" with the description "This is a test service." See Run Agent Service Install Command Examples below for more examples.

Run Agent Service Run Options

When you create your Run Agent service, in addition to the service arguments listed below, you need to specify the arguments for the settings you want your Run Agent to use when it runs. As described in Creating a Windows Service for the Run Agent above, the service launches the Run Agent using the same command it does when you run the agent from the CLI. You can specify the same run arguments for your Run Agent service as you would running it at the CLI. See Command-Line Arguments for a list of available Run Agent arguments.

note

The Run Agent command reports errors if the the command syntax is incorrect.

Run Agent Install Service Arguments

Service Install Arguments

Description

--win-service install

Creates a new Windows service that launches the Run Agent with any CLI arguments you specify as described above. You can also specify a service name and description for the service by passing the --service-name and service-desc options with the --win-service install argument. If you omit the --service-name option, the service uses the default name. (Default: DAI Run Agent) Once you create a service, you can see it listed by name in the Windows Services Manager shown above.

note

If you try to create a service with a name that is already in use by a another service on the machine, you see the error message: "The specified service already exists." The same is true if you do not specify a name for the service (by omitting the --service-name option) and a service with the default name DAI Run Agent already exists. In either case, you need to run the install service command again with the --service-name option and provide a different name.

Run Agent Service Install Command Examples

Note that you must specify the qualified path to the eggplantDAIRunAgent.exe in quotes as shown in following examples.

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service install --service-name "DAI Agent Service 1" --service-desc "This is a test service"

The above example creates a service named "DAI Agent Service 1" with a description "This is a test service"

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service install --ini-file [full path to ini file]

The above example creates a service that specifies the DAI .ini file to use. Because this Run Agent command does not specify the --service-name option and a name, the Run Agent creates the service with the default DAI Run Agent name. For information about the --ini-file option, see Command-Line Arguments.

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service install --ini-file [full path to ini file] --drive-port 5421

The above example creates a service named "DAI Agent Service 1" with specified --ini-file and --drive-port. See Command-Line Arguments for more details about available options.

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service install --ini-file [full path to ini file] --service-name "DAI Agent Service 1" --log-folder [full path to log folder]

The above example creates a service named "DAI Agent Service 1" with specified --ini-file and saves agent log files to --log-folder. Note: the folder must already be created for this command to work. See Command-Line Arguments for more details about available options.

Starting a Run Agent Service

Once you create a Run Agent service, you can start it in the following ways:

• Automatically every time the machine it runs on restarts, which is the default start-up type for this service.
• Manually using the Windows Services Manager.
• Manually using the Run Agent service --win-service start option at the CLI. Be sure to specify the service name if you have more than one Run Agent service with the --service-name option. See the table of Service Start Options below.

note

If you want your Run Agent to run as a service on the same machine where your DAI Server runs as a service, you need to delay the start-up of your Run Agent service until after the DAI Server is running so it can connect to it. You can configure this on your Run Agent service by configuring the DAI Server service as a Dependency. See this article for more information about service dependencies. You may need administrative privileges on the machine to set this dependency.

Service Start Options

Service Start Option	Description
--win-service start	Starts the service. If you have more than one Run Agent service, pass the --service-name option with the name of the service you want to start.

Starting a Run Agent Service Command Examples

Note that you must specify the qualified path to the eggplantDAIRunAgent.exe in quotes as shown in following examples.

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service start --service-name "DAI Agent Service 1"

The above example starts a service with the name "DAI Agent Service 1"

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service start

The above example starts a service without any options.

Stopping a Run Agent Service

You can stop a Run Agent service in one of two ways:

• Using the Windows Services Manager.
• Using the Run Agent service --win-service stop option at the CLI. Be sure to specify the service name if you have more than one Run Agent service with the --service-name option.

Service Stop Option	Description
--win-service stop	Stops the service. If you have more than one Run Agent service, pass the --service-name argument with the name of the service you want to stop.

Stop Service Command Example

Note that you must specify the qualified path to the eggplantDAIRunAgent.exe in quotes as shown in following examples.

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service stop --service-name "DAI Agent Service 1"

The above example stops a service with the name "DAI Agent Service 1".

Removing a Run Agent Service

You can remove a Run Agent service it in one of two ways:

• Using the Windows Services Manager.
• Using the Run Agent service --win-service remove option at the CLI. Be sure to specify the service name if you have more than one Run Agent service with the --service-name option.

Service Remove Option	Description
--win-service remove	Removes the service. The Windows machine will no longer run the service. This also removes it from the list of services in the Windows Services Manager. If you have more than one Run Agent service, pass the --service-name argument with the name of the service you want to remove.

Remove Service Command Example

Note that you must specify the qualified path to the eggplantDAIRunAgent.exe in quotes as shown in following example.

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --win-service remove --service-name "DAI Agent Service 1"

The above example removes a service named "DAI Agent Service 1" so that it is no longer registered as a service on the Windows machine and it is removed from the service list in the Windows Services Manager.